Add support for HCA tissue atlas (#7128) by dsotirho-ucsc · Pull Request #7877 · DataBiosphere/azul

dsotirho-ucsc · 2026-03-17T17:30:40Z

Linked issues: #7128

Checklist

Author

¹ when the issue title describes a problem, the corresponding PR
title is Fix: followed by the issue title

Author (partiality)

Added p tag to titles of partial commits
This PR is labeled partial _{or completely resolves all linked issues}
This PR partially resolves each of the linked issues _{or does not have the partial label}

Author (reindex)

Added r tag to commit title _{or the changes introduced by this PR will not require reindexing of any deployment}
This PR is labeled reindex:dev _{or the changes introduced by it will not require reindexing of dev}
This PR is labeled reindex:anvildev _{or the changes introduced by it will not require reindexing of anvildev}
This PR is labeled reindex:anvilprod _{or the changes introduced by it will not require reindexing of anvilprod}
This PR is labeled reindex:prod _{or the changes introduced by it will not require reindexing of prod}
This PR is labeled reindex:partial and its description documents the specific reindexing procedure for dev, anvildev, anvilprod and prod _{or requires a full reindex or carries none of the labels reindex:dev, reindex:anvildev, reindex:anvilprod and reindex:prod}

Author (mirror)

This PR is labeled mirror:dev _{or the changes introduced by it will not require mirroring of dev}
This PR is labeled mirror:anvildev _{or the changes introduced by it will not require mirroring of anvildev}
This PR is labeled mirror:anvilprod _{or the changes introduced by it will not require mirroring of anvilprod}
This PR is labeled mirror:prod _{or the changes introduced by it will not require mirroring of prod}
This PR is labeled mirror:partial and its description documents the specific mirroring procedure for dev, anvildev, anvilprod and prod _{or requires a full mirroring or carries none of the labels mirror:dev, mirror:anvildev, mirror:anvilprod and mirror:prod}

Author (API changes)

This PR and its linked issues are labeled API _{or this PR does not modify a REST API}
Added a (A) tag to commit title for backwards (in)compatible changes _{or this PR does not modify a REST API}
Updated REST API version number in app.py _{or this PR does not modify a REST API}

Author (upgrading deployments)

Ran make docker_images.json and committed the resulting changes _{or this PR does not modify azul_docker_images, or any other variables referenced in the definition of that variable}
Documented upgrading of deployments in UPGRADING.rst _{or this PR does not require upgrading deployments}
Added u tag to commit title _{or this PR does not require upgrading deployments}
This PR is labeled upgrade _{or does not require upgrading deployments}
This PR is labeled deploy:shared _{or does not modify docker_images.json, and does not require deploying the shared component for any other reason}
This PR is labeled deploy:gitlab _{or does not require deploying the gitlab component}
This PR is labeled deploy:runner _{or does not require deploying the runner image}

Author (hotfixes)

Added F tag to main commit title _{or this PR does not include permanent fix for a temporary hotfix}
Reverted the temporary hotfixes for any linked issues _{or the none of the stable branches (anvilprod and prod) have temporary hotfixes for any of the issues linked to this PR}

Author (before every review)

Rebased PR branch on develop, squashed fixups from prior reviews
Ran make requirements_update _{or this PR does not modify Dockerfile, environment, requirements*.txt, common.mk, Makefile or environment.boot}
Added R tag to commit title _{or this PR does not modify requirements*.txt}
This PR is labeled reqs _{or does not modify requirements*.txt}
make integration_test passes in personal deployment _{or this PR does not modify functionality that could affect the IT outcome}
PR is awaiting requested review from a peer
Status of PR is Review requested
PR is assigned to only the peer and the author

Peer reviewer (after approval)

Note that after requesting changes, the PR must be assigned to only the author.

Actually approved the PR
PR is not a draft
PR is awaiting requested review from system administrator
Status of PR is Review requested
PR is assigned to only the system administrator and the author

System administrator (after approval)

Actually approved the PR
Labeled linked issues as demo or no demo
Commented on linked issues about demo expectations _{or all linked issues are labeled no demo}
Decided if PR can be labeled no sandbox
A comment to this PR details the completed security design review
PR title is appropriate as title of merge commit
N reviews label is accurate
Status of PR is Approved
PR is assigned to only the operator and the author

Operator

Checked reindex:… labels and r commit title tag
Checked mirror:… labels
Checked that demo expectations are clear _{or all linked issues are labeled no demo}
Squashed PR branch and rebased onto develop
Sanity-checked history
Pushed PR branch to GitHub

Operator (deploy `.shared` and `.gitlab` components)

Ran _select dev.shared && CI_COMMIT_REF_NAME=develop make -C terraform/shared apply_keep_unused _{or this PR is not labeled deploy:shared}
Ran _select dev.gitlab && CI_COMMIT_REF_NAME=develop make -C terraform/gitlab apply _{or this PR is not labeled deploy:gitlab}
Ran _select anvildev.shared && CI_COMMIT_REF_NAME=develop make -C terraform/shared apply_keep_unused _{or this PR is not labeled deploy:shared}
Ran _select anvildev.gitlab && CI_COMMIT_REF_NAME=develop make -C terraform/gitlab apply _{or this PR is not labeled deploy:gitlab}
Checked the items in the next section _{or this PR is labeled deploy:gitlab}
PR is assigned to only the system administrator and the author _{or this PR is not labeled deploy:gitlab}

System administrator (post-deploy of `.gitlab` component)

Background migrations for dev.gitlab are complete _{or this PR is not labeled deploy:gitlab}
Background migrations for anvildev.gitlab are complete _{or this PR is not labeled deploy:gitlab}
PR is assigned to only the operator and the author

Operator (deploy runner image)

Ran _select dev.gitlab && make -C terraform/gitlab/runner _{or this PR is not labeled deploy:runner}
Ran _select anvildev.gitlab && make -C terraform/gitlab/runner _{or this PR is not labeled deploy:runner}

Operator (sandbox build)

Operator (merge the branch)

All status checks passed and the PR is mergeable
The title of the merge commit starts with the title of this PR
Added PR # reference to merge commit title
Collected commit title tags in merge commit title _{but only included p if the PR is also labeled partial}
Pushed merge commit to GitHub
Status of PR is Merged lower
Status of blocked issues is Triage _{or no issues are blocked on the linked issues}

Operator (main build)

Operator (reindex)

Operator (mirroring)

Started mirroring in dev _{or this PR is not labelled mirror:dev}
Started mirroring in anvildev _{or this PR is not labelled mirror:anvildev}
Checked for, triaged and possibly requeued messages in mirror fail queue in dev _{or this PR is not labelled mirror:dev}
Checked for, triaged and possibly requeued messages in mirror fail queue in anvildev _{or this PR is not labelled mirror:anvildev}
Emptied mirror fail queue in dev _{or this PR is not labelled mirror:dev}
Emptied mirror fail queue in anvildev _{or this PR is not labelled mirror:anvildev}

Operator

Propagated the deploy:shared, deploy:gitlab, deploy:runner, API, reindex:partial, reindex:anvilprod, reindex:prod, mirror:partial, mirror:anvilprod and mirror:prod labels to the next promotion PRs _{or this PR carries none of these labels}
Propagated any specific instructions related to the deploy:shared, deploy:gitlab, deploy:runner, API, reindex:partial, reindex:anvilprod, reindex:prod, mirror:partial, mirror:anvilprod and mirror:prod labels, from the description of this PR to that of the next promotion PRs _{or this PR carries none of these labels}
PR is assigned to no one

Shorthand for review comments

L line is too long
W line wrapping is wrong
Q bad quotes
F other formatting problem

codecov · 2026-03-17T18:33:52Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.77%. Comparing base (0ab9b8d) to head (f18e8bc).
⚠️ Report is 42 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #7877      +/-   ##
===========================================
+ Coverage    84.73%   84.77%   +0.04%     
===========================================
  Files          165      165              
  Lines        24074    24138      +64     
===========================================
+ Hits         20400    20464      +64     
  Misses        3674     3674

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

coveralls · 2026-03-17T18:34:59Z

coverage: 84.858% (+0.04%) from 84.818% — issues/dsotirho-ucsc/7128-tissue-atlas into develop

dsotirho-ucsc · 2026-03-31T16:20:19Z

7877_IT_2026-03-30.txt

achave11-ucsc

Looking good,

Consider adding the testing infra in an initial (maybe split) commit, it gives a stronger signal. As well a test case for None namespace in Nested.to_index/from_index round-trip.

achave11-ucsc · 2026-04-01T15:51:56Z

+            path = dotted(facet_path, 'keyword')
+            nested_agg.bucket(name='myTerms',
+                              agg_type='terms',
+                              field=path,
+                              size=config.terms_aggregation_size)
+            nested_agg.bucket('untagged', 'missing', field=path)


Since this is the same type of invocation as the one below, isn't a FIXME in order?

Additionally, you should consider not duplicating the section and just having the one FIXME, as it is now.

The FIXME is for a closed/invalid isseue (#3413). Removed.

achave11-ucsc · 2026-04-01T16:16:19Z

                        bucket['key'] = field_type.from_index(bucket['key'])
                        translate(k, bucket)
                try:
+                    # From a MultiTerms aggregation


Consider elaborating on this comment (and perhaps also the one in L423) as to why the MultiTerms aggregation isn't recursive.

Lastly, this comment is misplaced. It should be part of the commit which introduced the change.

achave11-ucsc · 2026-04-01T16:19:55Z

+                try:
+                    paths = v['meta']['paths']
+                except KeyError:
+                    pass
+                else:
+                    for i, path in enumerate(paths):
+                        field_type = self.service.field_type(self.catalog, tuple(path))
+                        for bucket in buckets:
+                            bucket['key'][i] = field_type.from_index(bucket['key'][i])


I don't think this is semantically neutral. Consider adding this as a subsequent commit or squashing it with the main changes.

Also, consider elaborating on the "Refactor method" commit message by adding some context, if you do decide to keep it.

This section should have been in the main commit, not the refactoring commit. Moved.

dsotirho-ucsc · 2026-04-01T23:28:47Z

As well a test case for None namespace in Nested.to_index/from_index round-trip.

The bundle 2c7d06b8 used in the new test cases contains both {'atlas': 'Lung', 'version': None} and {'atlas': None, 'version': None} tissue atlas values, which are confirmed to be translated with ~null in the test added to test_indexer.py, and translated back to None in the test added to test_response.py.

dsotirho-ucsc · 2026-04-02T01:18:29Z

7877_IT_2026-04-01.txt

achave11-ucsc

Approved ✅

dsotirho-ucsc · 2026-05-06T17:50:55Z

7877_IT_2026-05-06.txt

hannes-ucsc

PL today, please.

hannes-ucsc · 2026-05-07T16:27:49Z

+        is a flat mapping and includes the synthetic field 'accessible' that has
+        no entry in the plugin's field_mapping.
+
+        :return: dict with field names as keys and each field's type as value


Suggested change

:return: dict with field names as keys and each field's type as value

:return: a mapping from each field's name to its type

hannes-ucsc · 2026-05-07T16:37:54Z

+        result = {}
+        for field, path in plugin.field_mapping.items():
+            field_type = self.field_type(catalog, path)
+            if isinstance(field_type, FieldType):


TODO: investigate in which case field_type is not of type FieldType

The returned value from DocumentService.field_type() is always a FieldType, and there is already an assert in that method, so the assert here is unnecessary. I will remove.

hannes-ucsc · 2026-05-07T16:38:23Z

        )

+    @cache
+    def field_types_by_name(self, catalog: CatalogName) -> Mapping[str, FieldType]:


TODO: rename method to mapped_field_types(), use FieldName instead of str.

hannes-ucsc · 2026-05-07T16:38:36Z

            'is_tissue_atlas_project': any(bionetwork.atlas_project
                                           for bionetwork in project.bionetworks),
-            'tissue_atlas': list(map(self._tissue_atlas, project.bionetworks)),
+            # We deduplicate the `tissue_atlas` field values since duplicate


TODO: replace custom deduplication with an existing mechanism, and investigate why this is necessary since a SetOfDictAccumulator is used during aggregation.

hannes-ucsc · 2026-05-07T16:39:21Z

            else:
                return str(term_key)

+        if isinstance(field_type, Nested):


TODO: Rename nested_keys to nested_property_names. Remove nested_keys param from inner function choose_entry(). Populate nested_property_names with field_type.properties instead of agg['myTerms']['meta']['paths']

hannes-ucsc · 2026-05-07T16:40:05Z

                     type='terms')

    def make_facets(self, aggs: JSON) -> dict[str, Terms]:
+        field_types = self.service.field_types_by_name(self.catalog)


hannes-ucsc · 2026-05-07T16:40:39Z

+            agg.aggs.nested.bucket(name='myTerms',
+                                   agg_type='multi_terms',
+                                   terms=[
+                                       {'field': path + f'.{field}.keyword'}


TODO: use dotted()

hannes-ucsc · 2026-05-07T16:40:54Z

+                if isinstance(agg, Terms):
+                    # A Terms agg is for a single field, so we only put one
+                    # field path in `paths`.
+                    path = agg.field.removesuffix('.keyword').split('.')


TODO: Remove `.removesuffix('.keyword'), instead split first with an existing method, assert last element is 'keyword' and remove.

hannes-ucsc · 2026-05-07T16:41:04Z

+                    # these paths to the values in the aggregation buckets.
+                    agg.meta['paths'] = []
+                    for term in agg.terms:
+                        path = term['field'].removesuffix('.keyword').split('.')


TODO: remove duplication between if/else branches.

dsotirho-ucsc · 2026-05-19T18:25:40Z

7877_IT_2026-05-19.txt

hannes-ucsc

Index: src/azul/indexer/document_service.py
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/src/azul/indexer/document_service.py b/src/azul/indexer/document_service.py
--- a/src/azul/indexer/document_service.py	(revision c7ffa182dfc0426054dece0e6a841710c58ad5e3)
+++ b/src/azul/indexer/document_service.py	(date 1779471299837)
@@ -126,12 +126,10 @@
     @cache
     def mapped_field_types(self, catalog: CatalogName) -> Mapping[FieldName, FieldType]:
         """
-        Returns the field type for each supported sort and filter field, using
-        the name of the field as provided by clients. Unlike field_types(), this
-        is a flat mapping and includes the synthetic field 'accessible' that has
-        no entry in the plugin's field_mapping.
-
-        :return: a mapping from each field's name to its type
+        Returns the field type for each supported sort and filter field, keyed
+        to the name of the field as provided by clients. Unlike field_types(),
+        this is a flat mapping and includes synthetic fields like 'accessible'
+        that lack an entry in the plugin's field_mapping.
         """
         plugin = self.metadata_plugin(catalog)
         result = {}

hannes-ucsc · 2026-05-22T17:38:21Z

@@ -224,19 +223,4 @@ def _filter_schema_validator(self,

    @cache


Don't cache twice. Make a full pass over your changes to ensure that this problem doesn't occur anywhere else.

I can also only see one callsite, so you may be able to inline this method.

hannes-ucsc · 2026-05-22T17:42:09Z

        if isinstance(field_types, Nested):
            element = next(elements, None)
            if element is not None:
-                assert element == field_types.agg_property, (element, field_types)


Why did you remove this assertion?

My PR removes the agg_property property from Nested objects. Previously this property was populated with the first key in the nested dictionary (e.g. 'atlas'), and used in the nested aggregation path (e.g. path = dotted(facet_path, agg_property, 'keyword')).
With my changes, the nested aggregation now uses only the facet path (e.g. 'contents.projects.tissue_atlas'), and a multi-terms aggregation is nested inside which contains the path of each nested field property (e.g. 'contents.projects.tissue_atlas.atlas.keyword' and 'contents.projects.tissue_atlas.version.keyword').

hannes-ucsc · 2026-05-22T18:05:19Z

+            'tissue_atlas': list(unique_everseen(
+                map(self._tissue_atlas, project.bionetworks),
+                key=lambda d: frozenset(d.items())
+            )),


This is still semantically different from what the accumulator does. This uses all items of the dict while the accumulator hard-codes two specific keys. If we ever added an entry to the dict, the implementations would diverge. For Nested fields, you can assume that all entries of the value should be considered for equality between values, so this implementation is actually more general. Please, check if we can generalize SetOfDictAccumulator to have that function by default, if no key is supplied. If that's too involved, file a new issue. In either case, make sure that this here uses the accumulator, instead of reinventing the wheel.

Add tests

Implement support for aggregation of a nested field

dsotirho-ucsc self-assigned this Mar 17, 2026

dsotirho-ucsc linked an issue Mar 17, 2026 that may be closed by this pull request

Add support for HCA tissue atlas #7128

Open

dsotirho-ucsc force-pushed the issues/dsotirho-ucsc/7128-tissue-atlas branch from a5fa3db to 3fb45f1 Compare March 17, 2026 17:44

dsotirho-ucsc added reindex:dev [process] PR requires reindexing dev reindex:prod [process] PR requires reindexing prod labels Mar 17, 2026

dsotirho-ucsc force-pushed the issues/dsotirho-ucsc/7128-tissue-atlas branch from 3fb45f1 to 95a800d Compare March 17, 2026 18:22

dsotirho-ucsc force-pushed the issues/dsotirho-ucsc/7128-tissue-atlas branch 3 times, most recently from 080a58a to da4787e Compare March 23, 2026 23:49

dsotirho-ucsc force-pushed the issues/dsotirho-ucsc/7128-tissue-atlas branch 5 times, most recently from 1798785 to c0b9465 Compare March 30, 2026 23:29

dsotirho-ucsc requested a review from achave11-ucsc March 31, 2026 16:21

dsotirho-ucsc assigned achave11-ucsc Mar 31, 2026

achave11-ucsc requested changes Apr 1, 2026

View reviewed changes

achave11-ucsc assigned dsotirho-ucsc and unassigned dsotirho-ucsc and achave11-ucsc Apr 1, 2026

dsotirho-ucsc force-pushed the issues/dsotirho-ucsc/7128-tissue-atlas branch from c0b9465 to d67c292 Compare April 1, 2026 23:29

dsotirho-ucsc requested a review from achave11-ucsc April 2, 2026 01:18

dsotirho-ucsc assigned achave11-ucsc Apr 2, 2026

achave11-ucsc previously approved these changes Apr 6, 2026

View reviewed changes

achave11-ucsc marked this pull request as ready for review April 6, 2026 18:18

hannes-ucsc added 2 reviews [process] Lead requested changes twice and removed 1 review [process] Lead requested changes once labels May 1, 2026

hannes-ucsc assigned dsotirho-ucsc and unassigned dsotirho-ucsc and hannes-ucsc May 1, 2026

dsotirho-ucsc force-pushed the issues/dsotirho-ucsc/7128-tissue-atlas branch from 5b5526f to 0910a5e Compare May 6, 2026 16:27

dsotirho-ucsc requested a review from hannes-ucsc May 6, 2026 17:51

dsotirho-ucsc assigned hannes-ucsc May 6, 2026

hannes-ucsc requested changes May 7, 2026

View reviewed changes

hannes-ucsc assigned dsotirho-ucsc and unassigned dsotirho-ucsc and hannes-ucsc May 7, 2026

dsotirho-ucsc force-pushed the issues/dsotirho-ucsc/7128-tissue-atlas branch from 0910a5e to f18e8bc Compare May 19, 2026 17:03

dsotirho-ucsc requested a review from hannes-ucsc May 19, 2026 18:25

dsotirho-ucsc assigned hannes-ucsc May 19, 2026

hannes-ucsc requested changes May 22, 2026

View reviewed changes

hannes-ucsc added 3 reviews [process] Lead requested changes thrice and removed 2 reviews [process] Lead requested changes twice labels May 22, 2026

dsotirho-ucsc added 10 commits May 22, 2026 17:03

Remove obsolete FIXME (#3413)

9e87c45

Fix param description

05b1cbc

Change test data to use a valid HCA facet name

a8b7b20

Refactor method

2f679e6

Move functionality from QueryController into DocumentService

990076c

fixup! Move functionality from QueryController into DocumentService

41af090

[1/2] Add support for HCA tissue atlas (#7128)

53e3741

Add tests

fixup! [1/2] Add support for HCA tissue atlas (#7128)

74285b2

[r 2/2] Add support for HCA tissue atlas (#7128)

a4f1ff4

Implement support for aggregation of a nested field

fixup! [r 2/2] Add support for HCA tissue atlas (#7128)

767e6fd

	:return: dict with field names as keys and each field's type as value
	:return: a mapping from each field's name to its type

		@@ -224,19 +223,4 @@ def _filter_schema_validator(self,

		@cache

Conversation

dsotirho-ucsc commented Mar 17, 2026 • edited by achave11-ucsc Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Author

Author (partiality)

Author (reindex)

Author (mirror)

Author (API changes)

Author (upgrading deployments)

Author (hotfixes)

Author (before every review)

Peer reviewer (after approval)

System administrator (after approval)

Operator

Operator (deploy .shared and .gitlab components)

System administrator (post-deploy of .gitlab component)

Operator (deploy runner image)

Operator (sandbox build)

Operator (merge the branch)

Operator (main build)

Operator (reindex)

Operator (mirroring)

Operator

Shorthand for review comments

Uh oh!

codecov Bot commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

coveralls commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dsotirho-ucsc commented Mar 31, 2026

Uh oh!

achave11-ucsc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dsotirho-ucsc commented Apr 1, 2026

Uh oh!

dsotirho-ucsc commented Apr 2, 2026

Uh oh!

achave11-ucsc left a comment

Choose a reason for hiding this comment

Uh oh!

dsotirho-ucsc commented May 6, 2026

Uh oh!

hannes-ucsc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dsotirho-ucsc May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dsotirho-ucsc May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dsotirho-ucsc commented Mar 17, 2026 •

edited by achave11-ucsc

Loading

Operator (deploy `.shared` and `.gitlab` components)

System administrator (post-deploy of `.gitlab` component)

codecov Bot commented Mar 17, 2026 •

edited

Loading

coveralls commented Mar 17, 2026 •

edited

Loading

dsotirho-ucsc May 8, 2026 •

edited

Loading

dsotirho-ucsc May 7, 2026 •

edited

Loading

hannes-ucsc left a comment •

edited

Loading